USBMakeBMRequestType

The USBMakeBMRequestType function formats device and control request type parameters into the bmRequestType format, which are passed to the USL in the usbBMRequestType field of the USBDeviceRequest function.

The USBMakeBMRequestType function returns a UInt8 or 0xff if one or more of the parameters is incorrect. A value of 0xff is not a legal value and is not accepted by the subsequent control call.

OSStatus USBMakeBMRequestType(UInt8 direction, UInt8 type,
                                          UInt8 recipient);

direction

Direction of data flow, kUSBOut, kUSBIn, or kUSBNone

type

Definition of the request, kUSBStandard, kUSBClass, or kUSBVendor

recipient

Part of the device receiving the request, kUSBDevice, kUSBInterface, kUSBEndpoint, or kUSBOther

All USB devices respond to requests from the host on the device's default pipe. These requests are made using control transfers. The request and the request's parameters are sent to the device in the setup packet.

USBDeviceRequest

The USBDeviceRequest function performs control transactions to default pipe 0 (zero) of a device.

OSStatus USBDeviceRequest(USBPB *pb);

Required fields in the USBPB parameter block for the USBDeviceRequest function are

--> pbLength

Length of parameter block

--> pbVersion

Parameter block version number

--> usbCompletion

The completion routine

--> usbRefcon

General-purpose value passed back to the completion routine

--> usbReference

The device reference passed to the driver when it is loaded

--> usbBMRequestType

The usbBMRequestType field is made up of the direction, type, and recipient values

direction

One of the following:

kUSBIn Data will be transferred to the host.

kUSBOut Data will be transferred to the device.

kUSBNone No data will be transferred. The length and buffer parameters are ignored.

type

One of the following:

kUSBStandard A request defined in the USB standard.

kUSBClass A request defined in a class standard.

kUSBVendor A vendor unique request type.

recipient

One of the following:

kUSBDevice The request is to the whole device.

kUSBInterface The request is to a specific interface in the device.

kUSBEndpoint The request is to a specific pipe endpoint in a device.

kUSBOther The request is going somewhere else.

--> usbBRequest

Defined by the USB standard, defined by a class driver standard, or vender unique. See usbBRequest Constants

--> usbWValue

General parameter unique to the transaction request. This value is in host endian format, and will be swapped if necessary when it is sent to the device.

--> usbWIndex

General parameter unique to the transaction request. This value is in host endian format, and will be swapped if necessary when it is sent to the device.

--> usbReqCount

Specifies the size of the data to transfer. If this is set to 0, no transfer occurs

--> usbBuffer

Points to the data to be transferred ( kUSBOut request) or where data will end up ( kUSBIn request). The buffer should be at least as big as the size specified in the usbReqCount field. If usbBuffer is set to nil, no data is transferred regardless of the value of length

<-- usbActCount

Specifies the actual amount of data transferred on completion

--> usbFlags

Should be set to 0, or kUSBAddressRequest for control transactions addressed to an interface or endpoint

The request is sent to the default pipe 0 and the relevant data is transferred.

The flag kUSBAddressRequest supports USB control transactions addressed to an interface or endpoint of a device. The kUSBAddressRequest flag allows the control call to be made without the driver explicitly knowing the number of the endpoint or interface before the call is made. The USL fills in the interface or endpoint number in the setup packet based on the pipe or interface reference that is passed in with the call.

To use the addressed device request feature, specifiy the kUSBAddessRequest flag in the usbFlags field. If the recipient field of the BMRequestType is an endpoint or interface, the relevant endpoint or interface number is derived from the pipe or interface reference that is passed in the usbReference field. The interface or endpoint number is put into the WIndex field of the setup packet before the control transaction call takes place.

For additional information about the parameters specified for control transactions, see section 9 of the USB Specification.

If the request is a set_config request, the USBDeviceRequest function returns the same errors as those for the USBOpenDevice function. Other errors returned by the USBDeviceRequest function include

kUSBUnknownDeviceErr	-6998	usbReference does not refer to a current device
kUSBRqErr	-6994	the value in the bmRequestType field is not valid
kUSBUnknownRequestErr	-6993	request code for a standard USB call is not recognized